Tenets for formal document creation

An opinion – Onny Martin

(This is not a formal document!)

To encapsulate the subject in a few words:

Be accurate, thorough, say only what you mean and mean only what you say. Neatly.

Assume that

· Your intended reader will read your entire document and act upon only what is read.

· At some time in the future, you will be standing in court to defend your words. Thus, the extra effort needed to create a near-perfect formal document is worth it.

Then

1. Identify the typical or expected reader. Use language appropriate to your reader. What is the experience or education of the reader? Is an explanatory section needed?

2. Intent.

· A formal document says what it says. Only your words convey your intent, nothing else.

· The only person likely to have complete understanding of your intent is you. If your words are inaccurate, a reader cannot be expected to read your words to reach your intent.

· Avoid colloquialisms. Words appropriate for a formal document and colloquialisms differ.

· Review your document as a whole. You do need a good memory. Words in one place may be correct, words in another place may be correct, but they conflict when read together. Use “Unless stated elsewhere …” or “notwithstanding … “ etc. to avoid conflict.

· Use singular/plural or mandatory/optional (e.g. must/may, shall/should) with intent. “Will” refers to the future.

· Use correct grammar. Incorrect grammar displays a poor education (your reputation will suffer).

3. Thoroughness. Include all information that the reader needs. If your words are incomplete, a reader cannot be expected to read your words to reach your intent.

4. Clarity. A formal document needs clarity without ambiguity. With your thorough knowledge of your document’s content, you may find it difficult to spot ambiguity (see Item 12 Peer Review below).

· Never use passive voice: it automatically introduces ambiguity or lack of clarity.

5. Brevity. Only include words, phrases, sentences, data etc. that the reader needs.

· Where simplicity and complexity convey the same intent, choose simplicity. Do not try to impress the reader with your language knowledge (your reputation will suffer).

· Use the possessive case (an apostrophe) to replace words that convey “belonging to”.

· Avoid repetition. If necessary, use internal referencing to other clauses. You and your reader may share other, pre-existing documents: make reference to these – do not copy their words into your document.

· Use a “Definitions/Terms” section, helping to avoid repetition and improve clarity.

There are more than just the primary tenets above, for example:

6. Internal consistency. Do it the same throughout your document (words, phrases, syntax style, punctuation, verb tense, emphasis method, colours, formatting etc.). Often, English has two or more acceptable ways of expression or punctuation. Choose one and stick with it throughout.

7. External consistency. Is your document part of a larger document group or subordinate to a higher level document?

· Ensure consistency with documents of any pre-existing, larger document group.

· Ensure compliance to relevant standards set in or directives of a higher level document.

8. Logical ordering. Order your document to reflect any natural order in the physical world.

9. Backward clause referencing. Minimise forward referencing: jumping forward breaks the reading flow in a worse way than backward referencing (as you have no memory of the future).

10. Intentional gender. Only use bias when applicable. For brevity, add a phrase such as “’his’ shall be read as ‘his or her’” in an introduction.

11. Punctuation where applicable. You may ignore punctuation in a non-formal context. However, punctuation aids clarity. As a test, think of your words read aloud by a computer voice at a fixed tempo, without intonation, only pausing at commas, periods, colons, semicolons, brackets, dashes etc.

12. Proof reading and peer review. Accept it: like everyone else, including me, you are not perfect. Proof read your document (by those without technical knowledge) and peer review your document (by those with technical knowledge). If you find yourself in court, if need be, you can invoke peer review to argue shared responsibility for errors.

To summarize the process:

· Reader assessment.

· Intent with thoroughness, clarity and lack of ambiguity, brevity.

· Consistency and ordering.

· Proof read, peer review, forward to issuing authority, issue it.

Celebrate. Await the flak which, if the above is followed, may not be stopped but should be reduced.

--- End ---